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• -r ' Introduqtlon ^ . cc- " ] • 

• vocal' (Voice Oriented Curriculum Atithor Language) is designed to 
facilitate -the ** authoring of curfiquluns which incorporate h}.ghly 
ixjteraccive- audiq and t;e^t presentation; JLessons written in VOCAL, are 

/intended to be patterned after the style of - informal classroom lectures, 
VOCAL contains features that allow, the authoi-/ to ispecify audio messages 
in several formats acceptable to 'the audio -hardware, and associated 
sof tware, and to control the interaction^of' JChe audio presentation with 

'material presented" visually on" the sc 7 

Therfe are several, reasons • for incorporating, a^udia- messages -in a 
computer-assisted' instruction . course*, i One reason is to more actively 
involve the student in the, instructional process by using his. setise^of 
hearinflf in addition to his» sense, of; sight, A second' reason is - the 
. obvious^ advantage of having a .second' channel for communicating with the 
• student-*. A thirds reason is. that certain sorts of ..information can most 
-appropfia.tely ' be ]>resented , to thg;%studeiit via an audio cfcann^l* ' . For 
example,' it i-s of ten^'usef ul to maYeVinfo^al c;oiiments about formulas' or 
tables which Jare, sinultan^ousily being dispI^ayed'^V-Finally, certain kinds 
of semantic information are .usually carried^ by complex emphasis patterns 
in speech. Siich information can be d^ifficiilt or awkward, to reproduce in 
writing*. ; ' . /■ . . ■ f i ' ■ 

. - Given a system for generating andj* storing audio- messages fojr randoirf 
access by a* pxogram providing a course of study/ to students^ curriculum 
,authbirs neeja a' systematic w^y of in_dlcating^what ina^terial is to be 
. presente^ Jt^ the audio system,' and; what . material'^ is to be presented by 
di'splay or typescript. \ Authors *alsd. " need ' ways o5 indicating complex 
intomatiioa-aSout how the audio and visual modes of presentation are to 
^be.'fcoordinated, " Such facilities are -provided by VOCAL, as well as -more 
traditional "facilities such aS:' complex question and answer procedures • 
VOCAL \ has %also been 'designed' to' facilitate the addition of course- 
specif Ic exercises^^such. as proving theorems in; a logic co^irse. 

The syntactic structure, of, the language is. quite' simple and 
compressed, and is based on LISP-style S-expr^ssions. We selected this 
syntax ; because -it is. easily parsed and* compiled, and .the resulting 
language retains ."a flexibility and extensibi^lity that a more algebraic 
language might lack- ^he*. templkte features of VOCAL, are inspired by- 
features -of the PUB document - preparation language (Tesler, 1972).; we 
share with PUB the belief that! computers/ can do more text processing 
than ehey are generally permitted- The SAIL programming language (in 
which^ VOCAL is emb'edded) has contriblited some features- . The functions 
for .question/answer'' anaJLysxs -were_ suggested by such CAI languages as 
'INST and.COURSEWRITER. — , \'. / : ' . 

' While eVOCAL is "intendecf^to be general system^ for pref)aratioit of 
^AI materials utilizing 'audio,' we '/have included .\a number of special 
'functions - that relate to tlie particular use of VOCAL in vriting. 
curriculum fpr Stanford^'s logic and other^itiathematically based courses. 

Only limited programming features are included in VjDCAL- For 
example, only certain "conditional" operations'^^have ]been programmed, and 



Section 1 * " - / Introduction^ 

• ; / . • ■ , . • .'^ 

no- explicit data declarations qre available* VOCAL is not a general 
. plrogranming language. Vlnstead', it is a language for tightly expressing 
particular interactions between the audio output, the visual output, an4 
th^ student. Our implementation emphasizes the interface between 
programmlnj^ , which is done in SAIL or LISP, and authoring , which i$ done 
in VOCAL. « : - ^ 

A classical problem in designing an author language is that, on the 
-Cfne -hahJ^v- one -wants a language - that authors - can use with -minimal - 
^training in programming, a language in which presentation of materials 
and response Judging will be straightforward; on the other hand, it is 
often necessary _ to have a genuine programming language, with 
^sophisticated data , and -control structures, for application ^ in CAI 
'environments thkt , emphasize problenl solving, dialogue, an9 the like« 
/Some. CAI languages solve this problem by^ restricting what is possible or 
,^ convenient ^ to dp (INST, ^f OURSEWRITER) ^ other languages maintain the 
I claim t6 universality, but^do so with data a^d"~control structures that 
' are quite primitive (TUTOR).' The current popularity of BASIC as an, 
'author language can be traced to the fact that it^is^quit^ simple and 
yet is a complete programming language; it is also widely available. • 

We thinlq that a Better solution to the problem of authqr languages 
is. to select the oest programming languages available for writing the 
program portions of the CAI system, and to interface the resulting 
programs to. Special-purpose author languages for the curriculum 
loaterial. VOCAL/ is' such a special-purpose language. 

t This report is intended .primarily as' a descripC^ion of the VpCAL 
language and its features. Readers who are iirter^sted iii * the 
pedagogical applications . of the langfiage or, who would like a^utorial 
introduction- to the use. of^^VOCAL should see (Davis and Pettit, 
forthcoming), a. useful .supplement to the material in thi^^^ocument-. 



J 

2 The VOCAL Language - • ; .r^' 

This section describes the syntax and semantics 'o*f the VOCAL' 
language. At short overv:^ew 'of the various^ operation _codes (opcodes) 
described below may hel^'in clarifying their uses. * ^ 

The lesson; EXERqiSE, BEGIn and HOLD opcodes serve the purpos^e ^f 
organizing pot en tial'Ly. vast amounts, of ^ curriculum material for bot^ the' 
curriculum author and the student. TJhe display ■ opcodes (such;' a^ TEM, T; 
B, etc. ) all<5w the aut^hpt v to . specif y what material ' will ap'^eax on the • 
display terminal screen and^its farmat* In addition', 'the author can 
seperately specify -the order' in which th-e material is displayed. 

The audio opcode, S, specifies what material is to be spolcen. When 
,an opcode which xoatrols the (fisplay oh the screen is followed by a text 
string (both within. th,e scop^ of . the same 'S opcode) the audio system 
will' begin speaking th6 text ^at the same time fhat the di^lKLay system, 
begins to execute, the <iisplay o^gcpdej* \xhis allows the curriculum "author 

r 
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to syncronize the audio and display systeinsL,, There are also timing 
opcodes which give the author additional contnol^ • • 

The quest ion-;-r^lat(^d opcodes -are used^ to present students with-^ 
short answer questions and. to analyze- th^ student y6 input. The author, 
is allowed to si^ecify the number of -chances the $rcudent has to answer, 
the i^ogram's 'response to correct or incorrect Answers, whether to 
•respond differently to Specific correct- or;^ incorrect answers, ^nd 
whether to ask further questions ol students who fail to correctly 
answer a " qixes tiori^ Facili ties are "jj^r^ th~e"s~t udent~~as" 

to time and manner of required^^response* -.In 'most cases, the authot can 
accept reasonable defaults in the question and answer procedure if he 
does not desire to use all ofi the availa'ble features* 

The conditional opcodes AUDIO, NONAUDIO, DPY, and TTY, are used to^ 
indicate^^alternative code j^to '^"be executed depending on the type of 
terminal at which the "student is \^orking.^ The concern is whether the 
trerminal .^allows sufficient control' of the display for the DPY and. AUDIO 
versions, and whether the terminal is provided with the appropriate 
audio equipmeiJt. - ^ ^ f 

The branching opcodes allow the author to control the progress of 
tho, - student, through the curriculum. At a minimum the author, should 
specify a linear move from ' Ifesson to lesson by including a GOTO ^t the 
end of each lesson, pointing to the next lesson- "^ore complicated paths 
can be arranged' by the author, where final choice of path for an 
individual student^ nay depend u^orr his own choice or upon his meeting 
sbme preset^' ©ritericfn. ' 



2*1 Conventions 



The basic syntax of VOCAL is simitar-to LISP 1.6. The S-expre'ission 
'is use<i to code the instructions. The- CAR (first element ^of the list) 
is the name of the operation code ("opcode"). Just as in LISP, the CAR 
of a list is treated as the "name of a function. (tecodes may embed 
within each other* Indeed, ""it is the power of* emb^ding, so^ feasily 
"achieved with th6 LISP syntax, that has led us to the choice of a very 
LISP-like /syntax.^ - . . • . ' 

/ . For example, the following VOCAL statement defines 'the- body of an* 
exercise (number "1") in a lesson:, * / 

' . . ^ .' 

[EXERCISE 1 "Sample, exercise" ^ ^ \ 

(AUDIO 

^ .^^(T "This* i^ the text pf thje exercise^?") ^ • . 

I / '(S'^"irotice the text of .the exercise on^ the screen.**))* 
(NONAUDIO '/ ' ' . ^ / ' 

(T '"This is thd text of the exercise."))] ' * * 

The S\ and, T. opcodes, -respectively, speaks and type their^ arguments. The 
AUDI^/opcqde says that the statements .contained within it3 scope are to 
be '^one if the studint is presently using th^ audio sysfcfem. Tiie 
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statements within the scope of the NONAUDIO opcode will be doae' if the 
student is pot presently using the aiitfio system. The ^erxtire text of the 
exercise is surrounded by the EXERCISE opcode. 

'Like some ver^ions^ of* LISP, the VOCAL language allows the use of 
square-brackets in place ^of parentheses. ' In addition to ^closing t^ 
most recent' left square-bracket, a right square-brackret will -close any 
open left par-entheses within the scope of the squaje-bracket pair. 
-Judicious - use— of _s<iuare,-brackets . _wilJ^ enhance -the-.readability_.__of ...the. 
lesson source file and serve as a debugging aid by limiting the scope of 
a parenthesis mismatch error. ^ 

In the sequel several convention^ will be used tp state the details 
bf the ' language^. The term "string" will refer, to a literal string 
constant, i.e., a piece of text surrounded by quotation marks. Tokens 
in upper c^e are VOCAL opcode names. Tokens in lower case, surrounded 
by >V,rare metalinguistic. . 



2.2- LESSON Opcode ; 
The lesson opcode is syntactically of the form: ^ 

^ (lesson'' <number> "description" <actions>) - 

.where: / 

■■ . . .. - ^ 

<numbe,r> is the lesson number* 

... * » - 

"description" is a. single line "description of the 
^ lesson. " " / ^ 

^.A • > — ^ / 
. <actions> is an .arbitrary sequence of VOCAE .-. 

actions to be performed if the student, 

^ in "Browse Mode" (see Section 3), asks 

\ " for information about this lesson. 

The LESSON opcode should occur only once in a given VOCAL file* 

. ■ . " ■• J / • ■ ' ■ 

2.3 EXERCISE Opcode I 
^ The EXERCISE opcode has the syntactic form: 

•■ ' • . • 'I v " ^ . 

(EXERCISE <number> "de^ription" <actionsO} 

where: ' . . . tr^ ' - . 

<nuraber> is the -number of this exercise- - 

*'description" is a one-line^ description 5f this. ^ 
exercise, to . apped'r at the .top of the. 
display screen'. 
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<actions> is the sequence of» VOCAL actions for 

tKi^s exercise- . . ( ' * 

An'- EXERCISE is an entrjf into the curriculum, the smallest unit that can 
* be randomly accessed, VOCAL files should "therefore have the following ' 

^ ■ w . , 

[LESSON n "lesion description string" ^ctions>]/^ 

[EXERCISE.-1- -factions >] ! J : „ 

'[EXERCISE 2 ^'1..", <:actions>l - . . 

(EXERCISE n <actions>] 

' Only compiler-specific opcodes should occur , outside the scope of a 
LESSON or EXERCISE opcode. If there is another lesson to- follow, the 
GOTO opcode should be th^rjJLast action of the last exercise. 

\ . * * « 

I 2,4 / BEGIN Opcode • ' • ' 

The- BEGIN opcode groups together a number of statements thaL are to 
be executed as a single unit. For example, ■ , \ . 

{BEGIN (T "Now is the time for all good men") 

(S "Now is the time for all good men")) ^ ^ ' 

both types ana* speaks "Now is the time for- all good men". Note that a 

list of lists, e.g. ( (T " ")'(S "...\") J, begins with an implicit 

BEGIN. * ' ■ ' 

2.5 Display Opcodes 

The display screen is divided into four portions. The first 
portion is a single line, called the Description Line. This, line is 
reserved for the "description" string of an EXERCISE qpcode or its 
analogue "in Help or Browse Modes. One of its major functions is to ftelp 
the student keep track of where he is. The second" portion is. called the 
Template Region. It gets its text from the template. string as described 
below. The ttrird region is a single? line, called the Mark Line. It 
serves-as a visual* delimiter between the Template Region and the fourth 
region, which is- called the Scroll Region. Some opcodes place text in 
the Scroll Region, -but the text" is always added to ^he bottom line of ^ 
the screen, and old pext moves upward, to disappear when it reaches the . 
Mark Line.^ - \ ■ ^ ' • ■, 



^Ttfe screen is 'manipulated using a device-independent display 
package developed by the systems staff at IMSSS- The , advantage of this 
approach is that neither th^ lesson autho^r nor the program author needs 
to be concerned with producing different code for the various kinds of 
display terminals in use at the Institute- ^ \, 



m 



(section .2.5 \ Display Opcodes 



The syntax for setting up a template region is discussed -in the 
section pn template opcodes; the syntax for controlling run-time display 
of text'* in the template and scroll* regions is discussed •in the' section 
on .display-control opcodes*^ ' ^ . ' . r 

.2.5.1^ Template Opcodes ^. ^ ^ 

The TEM ,an^ ?!)pcodes up a templsate, described below ,t _^^.^.g^. 

contains the dis'pl^y^d text. The syntactic form cf TEM isx y^^^ 

Si 

(TEM "template string" <acr^ons>; . 

TEM2 is an extension^ which is described Tjelow. ' ' • • 

The "template string" *is an image of the display scvreen. This- 
image contains area pointers that po;lnt to logical lines ^ groups of 
lines > ax^ contiguous segments of litles* , 

'The : ken "<actions>" indicates a sequence of statements that are 
execute:.. ...y opcodes for display control (see below) may refec to the 
logical areas of the template. Tften the-template is entered, the\^creeri 
"is cleared (except fpr line 0)^ 'and the scroll poipt is. set to the line 
that is the bottom^ the template. TEM opcode cannot contain another 
TEM opcode; in other wbrds, the templates do notr embed. ^4 

The "template string" is; a stririg cojistant that/ qXI^mis one to 
print, .overprint, ^rase, or brig"hten aT3^ part . of the template. 

p ^ ^ ■ . / ; , 

(TEM2 "template string" "additional string" <actions>) ^ 

This is like TEM except that the additional string", may contain areas ^ 
and subareas that are to be overtyped ^by the OT opcode or its relatives. 
The template string still defines the shape of Vthe ^template. Details 
and restf'xctiohs are indicated velow. / ^ ' ■ ^ . _ - , - 

'2.5.2' Areas ;! Subareas Within a Template * 

The template string* serves several purposes simultaneously. ^^^^irS^ 
the total number of texz lines, including empty lines, determines the 
size* of the tenplate region. This is currentTly limited to 19 lines of 
text since the Datamedia terminals, which hold ^ *maximum of 24 lines, 
are 'the limiting case.^ At , least th^e lines are needed for thje Scroll 



'"^How the text is B^ghtened depetids on the hardware. On soi|^ 
terminals the text is printed in double-intensity mode, hence the te^^ 
^brightened'. On other terminals the text will be underlined arid on 
still others^ the text will blink or f^ash* ' • 

* o " ' . . ^ ' ' 

"^It is usually a good idea to leave the first* line of text blank to 
>erve as a visual delimiter between the Deicxiptiori Line apd tiie text, 
•so in practice titere are 18 lines available for text.. - In exceptional 
cases the limit can be extended to 21 lines, leaving only one line for 
the Scroll Region. ' But this is rarely a good idea. 
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Reglon>. and^ the Description and Mark Lines each take * one. Second,^ the 
text which will appear in the Template Region is introduced. And 
finalliW associations • are made " between *the text and parts of;*, the 
template region. There are two ways of explicitly designating parts of 
the ^template.-^ One-way is ^ to give a .name to a olirfe or group * of 
coritiguous lines, which -^iW^ jthen called an area, and specified by 
using .the specia'l character The other is tcN designate - a 

contiguous" part of a single line as a subarea. , " , . 

• Considej: the following template string: 



(DP. 

. A 
(2) P -> Q ' 

B ce 



(2) means that % 

' -if P iSt true ^ %_ 

, EEEEEEEEEEEE , 

then Q is ti'ue %3 



In the above sample template string, the lines that contain are 
des.ignAted as the b^a^inning, continuation, or end . of an area_ spanning 
one or .more complete lines. Lines -that end with^"%" mark -the first line 
^ of an area that is' to extend bver two or more lines^ with the ne^t line 
^ that' ends with "%<numb^>" being the final line of that area* .Note that 
once a multiline area* is b^un with a line ending with (or with 

the area is t'er^ninated only by a line ending, with "%<numbe'r>". 
here , may"" be intervening lines ending with that are "^simply 

/continuation lines. - - . . ^ 

. The most complex cases are the lines that end with either or 
. "Z<number>_". The first of these says that the next line is not 
, actually to 'appear on the screen, but instead will contain subarea- 
'^designators^ ii\tq the current li^. Thus, "if P is^ true" is designated 
' as a"' subarea (named "E") consisting of " a . number of column positions- 
Likewise, a . line- that ends with • "%<number>_" say^ that <nuinber> marks 
♦ the ^current linens) as an area with name <number> but tHat , :in /additio.n', 
parts of the current line, will be marked by the area designators on the 
next -line. ^ " . ' ' • ' ' *• ^ ^ ' 




^^This character is dynamically resettable using the TEMCHAIt opcode, 
q .v- * . : 

^The "^" symbol is special, only when it occurs to the right'bf a 
"%". Otherwise it is treated as ordinary text. 
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V 



Note: Area "and^s^afea ^designators nev^r' ^pear •^.on the^screen* 
The .compile£^ uges them to give names to areas and* subaifeas and then" 
.discards them* For example, if an author reqizested ^liat areas 1^" 2, add 
" 3 of the sample ' template >s^ing above Be d;isplayed^. on >tbe screen, the 
student would see the foll'o>^ing: . ' 




■ (2).'means that \ V T • * ^ 

^ _ if P is true , A. * " ' 

• • ' . then'Q is. ti^ - . ^ ' 

<numbpr> can any p6sitiv^-':lnteger ,r -et^g, 7 or 32» A subareja. 

designator can be . any ■ 'alpl^abetic' character*. ^ BUT CASE - MAKES A 

DIITERENCEI In oth^r words/, the ^compiler will distinguish betwee^^*'a" 
.and "A". This^ gives a totals of/ 52 distinct subarea -designators*^-' A 

subarea .designator can be;^ used only once* in a template string and 'all 
' occurrences- must be contiguous. So "AAA b C" and "AAC b" are; legal, but 

"A A'b" and^'4i)A" are'^not. . 

Several opcodes — T, E, D, OT, OB, OE-^may 'refer to areas of . th^? 
current template ^y being Included- in . the .'<actions> list within the 
.spope'of the template. This is explained below. 



2.5.3 ■ ' Display Control Opcodes 

' i ' y ■■ . 

' The following opcodes generate the display on' the screen* The 
metalinguistic "<areas>" means any sequence of ^rea or subarea 
designators that occur in the scope of a JEM or TEli2 opcode* It is^ an 
error to have an area reference that does not occur within the scope -of" 
TEM or TEM2. ... * . . v v . 

' ■ - . (T <aLreas>) 



Each area in- <areas> is ^ typed out in the appropriate region of the 
template. <areas> can be replaced by a string constant which will be 
typed out in the Scroll Riegi on* ^ " 



(E <areas>) " ^ 



Each ar^a in <areas> is Erased, leaving those areas blank on the screen, 
but .leaving the remainder of the screen undisturbed- fhe action (E) 
with no arguments erases the* entire template, (but not the Scroll 



Region) . 



(B <areas>) 



"^if 'npre than 52 subarea designators ares needed, the digits are 
ailso legal subarea designators provided they are not 'used as area, 
designators* This could . be accomplished by using two-digit area: 
designators* - 
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JSIach area in <areas> is "Brightened"~typedi: but lin double intensity 
''mode, Vlink modei or underline mod? depending, oh the Rnysical -device 
availabr§;and its characteristics. ^ • *.] ^ ^ ^ 

(U <areas>) 

. - - ' . ' " V ^ , " ^ ' 

Each area in'<areas> is. VUnbrightened" — leaving the text t^ed out. (U) 
with no arguipents unbri^tens all brightened areas. /Note? there is no 
implicit^'^unbrightening'i ^so if an atithor wishes to restore an area to 
nonn^l^ state', he must expres^sly : ^nbrigh ten that area. .Dnbri^htening 
restores the text; 'to ersTse use the E opcode. If an^^area has beet! 
/ erasefd, unb|righ.teaing it causes' it to b^retyped in normal mode* 

* The M (for "Mark screen'') opcode prints a dotted line on the Mark Line 
of the, ,'dis^J.^y region in a XEM or TEM2 opcode. A - dotted line is 
inserted there automatically by the first Q or CQ opcode executed within 
the XEM- or TEM2, so "when these opcodes occur within, the scope of a TQl 
of TEM2, the M opcode merely allows the author to insert the dotted* line 
sooner if he wishes. * ^ , , 

^ ' ^ (OT*<oldatea> <newarea>>- • ^ 

OverType <oldarea> with <newarea>. The text from <newiarea> is -picked up 
and inserted into <oldarea>. • <oldarea> must be a single area in the 
"template . string" of a TEM2 opcode-, and * <newarea> must be -either an area 
in the "additional string" of a TEM2 opcode, of a string constant tliat 
is just printed in <oldarea>.. If <newarea> and <oldarea> are/ not *the 
same size, the text o^ <newarea> will be adjusted to fat <oidarea> by 
, truncation \?r Silling in with blanks of blank lines as require<f. It is 
better 'for the author to ensure that ^oldarea> and <newarea> occupy the 
same numb.er 'of lines; the result will then be obvious. 

(OE ^*<oldarea> <newarea>) • 

OverErase <oldarea> with <newarea>. This is the same as OT, ^only the 
<newarea> is not-" displayed; <oldarea> is erased, and <newarea> and areas - 
sharing screen locations with it (see below) become defined. - 

(OB <oIdarea> <newarea>) . ^> 

OverBrighteti <oldarea> with <newarea>» The same as OT, onl^i^^^the 
<newarea> is displayed in brighten mode. ^ - 

-V - ' \ ■ . 

2.5*4 RemaiJks on the Implications of Overtyping . 

^ ^ ■ ' ' ■ .. ' 

^ » • r ■ 

• In tfee-'^simplest case, an "area". or "subarea" is defined to be a 
region on the display screen plus the text that is currently displayed 
there. However, in the case of a ^subarea, this is not quite true — since^ 
the text of such a subarea is shared with the text of an area containing 
:the entire line. When using the TEM2 opcode it is important to keep in 
mind that it is the first template string that defines the basic size 



Sectioji 2*5*4 Remarks' on the Implications of Overtyping 



and shape of ' the Display Region. But '^the conventfions are somewhat 
different for subar^as* We illustrate the', convent ions by examples ' 



/ 



-p- Now. is the time. %1_ 

: AAAAAA . * . ■ ^. 

?^ -* '* Hefe's a good example* %2_ 

- ' - BBBB'BB CCCCCCC / ^ , . > 

^ If the opcode (OT d 2). is executed, the .-VOCAL convent ion is that 
area 2 becomes actively -defined in the ^^emplate region* For examplev (B 
1) and (B 2) will both cause "Here'sva good example J" to be brightened 
on-line 1. But the convention for subareas is different. When (OT 1 1) 
•or" (OB 1 2) or (OE 12) is executed, the subareas of area 1 are no' 
longer active. Instead, the subareas of area 2 become activated. So (B- 
A) xs no longer legal at /that point. 

■ > 

It is clear that some convention is necessary; otherwise* after the 
opcode (OX. 12) in' the example, the opcode (B A) 'would.be ambiguous*, 
c The convention chosen will generally . work to the lesson author ''s 
advantage by simplifying the task of brightening small areas after they 
/have been displayed on the screen as a resultr of overtyping* 

■"■ ' 

The compiler will not complain if a Subarea instead of an area is 
used within 'the scope of an OT, OB, or OE^ %code, but th^' resulfe may 
well not be what was . d^ntuitively expected-^V^^ fact, one of the major 
uses of the OE opcode is not only to allow an "old" template ^area to be 
erased, but also to activate 'the subareas in the new* text string, so 
that a call such as (T B) will have the desired effect. 

• ' ' ■ . ; ^ 

2. 6 Audio Opcode^ 

The S opcode is interpreted by calls to functions in^ the audio 
library, written by W. R. Sanders and G.^Benbassat. 



• (S <display!action> "message" <display!action> "message"'...) 

This .is tl^ general form of the Speak opcode. Each <display!actida> is 
either a dxsplay opcode or a list of display opcodes (all other opcodes, ^^t- 
except W, are illegal), e.^, (B ^4 A) or ((T 4) (B E) ^(T F)). A 
<display!act-ion> is. executed simultaneously .with the speaking of the - 
following "message". ^ The opcode is implemented- so that the "messages" 
are spoken continuously without interruption; that is,, the. "messages" 
/..are treated as a - single paragraph. Thus, the lessoii^ author can 
synchronize the screen display with a specific word in ':^e sentence. 
VOCAL' 'will wait, until all speaking and other' actions a^.,;;^,(:ompleted 
before beginning .the next opcode. ^All. of the <display!actiQhs!> and aU 
but one of the "messages" may be, omitted. For example: 



^See Sanders et al. , 1976 for an overview of the .iiudio system. V 

r - > ' . ■ 

ERIC -• 15 ' . ■ .. 
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• (S "Now is the time" * "Bujr bonds") ."for ^ll*-good men") .\ 

will display "^-Buy, bonds" ; just as? "for all good meri'* is being spoken. 
Cave^: Only the start •times of ^ the <displayiactiori>s and spoken 
"lalg^sagesV . is coordinated. Thus,' if * the execution ' time ' for 
<display iaction>' exceeds that of the - following-^ "message", lat^r 
. synchj?pni?ation may be lost* Unde^* heavy'^system load, execution times 
for the <di splay i act fon>s will of course increase. The "author s'hould 
take note of this when deciding how; many "messages" «and how much typing 
. to include within the scope pf a single S- opcode. • 

, Exactly, how^thd*: /'messages" will b'fe spokeh depends on the current 
implemeiitiation'. Brief ly,^ messages . may* ^be prerecorded, and processed for 
-storage a '^compressed' -farm, or the messages^ may be '^constructed' at 
compile, time from prerecorded words or- morphemes, witK syntactic 
prosodic^ features* added, by ^ the compiler^ The fprmer method is referred 
to as "^long sounds',, the latter as ^prosody'. ^ - 

• ^ . _ : . '.. • ^ / . 

At least two audio languages' are available to lesson authors. 
The Ifanguage for long sounds^is the compressed, digj^tfzed representation 
^ of t^e^^^corded phrases.. -A language for prosbdjf ^i-ll generally be a 
dictionary of recorded words, also in compressed, ^gitized form. The 
language opcode allows the author to change the language or mode of 
audio presentation- within a lesson. ' ' . . * 

(LANGUAGE "audio language name" "long sounds flag" "prosody flag") 

'If .the string "long sounds flagV is set. to "TRUE'', fhen the student 
hears long sounds. ^ If ^long sounds f lag'^is set to "FALSE" and "prosody 
flag" is set to "TRUE", then the student hears prosody^v The author must 
select the proper language in each case. If the "ipnig sounds flag" and 
"prosody flag" are both set to ."" (NIL), then the mode of aiidio 
presentation will remain unchanged, allowing a change of ^anguage only. 
It is possible"* to change langucifees without, changing the mdde, as long "as 
the unit of recording (word or phrase) is the same for both languages. 
It is NOT, in general, possible to change, modes "without changing the 
language, since the required unit of recording wiLl^%e different for the 
different modes. Thus, if the author wants to shift from long sounds 
mode to prosody mode, he must also, switch from a language of stored 
phrases to ^ language of stewed words. I • ^ 

■ x ■ ■ - ■ \ 

In an effort to include special (semantic) " emphasis in* the 
'^prosody ' versfion (and, in addition, aid a human "recorder), - emphasis 
markers are available to lesson authors. $<num> (followed by a space) 
may be inserted before the word to. be emphasized' in the speak text. 
<num> may be either 1, 2,. or. 3, where 1 indicates the greatest stress 
and 3 the least. All three give an ' iticre^se . over the normal, 
syntactically generated^ stress. For example: 

(S "$1 Now is the time 'Ic or all; $3 good men") 

will put a great deal of "stress on the word ^now.' and just enough stress^ 
on *good^ to cause a listener to pay some extra attention to the word.. 
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See Appendix B for details. 



Section 2*7 - j • ' Tinring Opcode 

^ii7 . Timing Opcode ^ . " V * 

Most -of the timing and synchronization is handled automatically^ by 
the compiler /driver '(see the "S"- opcode above) There are a few cases 
where -authors-* will wish to specif y > short hreaf in . the presentation, 
such as at ^the end of* a logical "paragraph" of the lecture. This is 
done by the W opcode. ! • ^ - y 

' " ^ ' ■ (W <mstime>) 

<mstime> is the number of milliseconds for the dismiss. If <mstime> is 
missing; a default value is used, determined by ^-tjie compiler. 

, . '■ \ ; V V ' ' " ^ • : ^ . - - ' / . : 

/ > 'The W opcode is the only nondisp'lay class opcode, that is legal 
inside the scope of an S opcode. There, instead of generating a 
dismiss, it causes- the audio hardware to -generate silence for the 
indicated number of milliseconds. At times of higher sj'St em* loado^'s 
outside ther;.&cope of S .opcodes will produce pauses of greater length 
than their arguments, while W^'s inside the scope of an S opcode \dLll 
not. . . / 

' Inside a speak, the W opcode functions .exactly as a message string; 
Pietceding display actions are exec^uted just as the silence begins its 
execution; . subsequent - display actions are executed^only after the 
Specified time of- silence. The syntax for the W opcode outside of an S 
opcode is the same as that of any action. Inside the sbope of an, S 
opcode, the syntax is'^^^e following: A W to be. executed with a series of: 
actions shoulci be included as the last of the actions in an implicit 
BEGIN. Actions that are intended to be executed after a W should be 
enclosed in a separate implicit BEGIN. Also, a W oj>code cannot Be 
immediately followed by another W (this is' of course no sema n tic 
restriction, since the* same effect is achieved by adding the arguments) 

- (TEM " ' 

. . Pick the correct answer ^ . 

AAAAAAA . ' ; " ^ 

'* . * 

• . ■* \ ■ ^ . * • ^ 

. (S "Pick the correct answer,'^ 
• ((T 1) (W 1000)) ((B A) (W 5^0)) 

"to the next question.")) f 

\ , / ^ ■ • ; :^ - . : ■ V • A 

The effect of the above code w^ld be that first the phrase •'*pick- 
the correct answer' would be spoken, second the phrase would begin to. be 
typed, and simultaneously there would begin one second ^of audio silence. 
The word ^correct' would be brightened immediately^; after either the 
second of silence, or the typing of tlie ^phrase, depending on which takes 
longer i In' either case one half -second- of silence would begin 
simultaneously with the brightening action, and at the completion* of 
both the 'audio silence and display actions, the. phrase ""to t~he next: 
question' would be spoken- . . ; . 
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2.8 HOLD Opcode >. ;^ . • . , 

. * ' _ . . * . ' ' •' 

Tlje're are numerous opcodes in. VOCAL that ask for a response from 
thejstudent* Jhe /simplest of these allows the student' to state when he 
is ready to ^continue. This "is the HOLD opcode. ' 

• • ^ . ^ ^ " ' . • ' 

. . > ; JCHOLD .^'promjit string" <actions>) 

^ • • ♦ 

In- its simplest*^ form, (HOLD), * the HOLD opcode 'simply ty^es out . 

'X^ . - • ^ • • • 

EType ESC to go on»] " 1^A^''^>•^ 

and then waits for the student' to type something bief ore continuing. The 
puorpose of this opcode is to let the student judge whe'ntae is finished 
examining the display. No answer analysis is done; howevW, functions, 
like logging out. Browse, Help, and repetition of text all- yoric f^om 
this opcode, since thfey are embedded in a lower-level f^jaiction 'in the 
interpreter* ( * <= 

The HOLD opcode may also take arguments. If the first argument 'to 
HOLDl is a string . constant, then that string i^ embedded in the prompt 
. str^nj^: ^ ^ • • ' . 

"[Type ESC to go ;on, CTRL-A to " + "prompt string" + "•]'-' 

So, if 'prompt st^ng" werje "repeat^ the argument", the_ result would be 

"[Type ESCVto" go on, CTRL-A to repeat the argument^" 

I * 

%f <actions> is nonempty, but "prompt , string" is omitted, ''the default 
-pMmpt string is "repeat". <Actions> is a -sequence ^ of opcodes to^ be 
executed before the HOLD is done (and to be repeated on receipt of CTRL- 
A). It is recommended that small reentrant blocks of code, i.e., blocks, 
of code that can be re-executed without obtaining a poor effect oi> the 
screen, be surrounded by HOLD in -order to give the student a .chance 
repeat> should he not fully understand them the first time. 




- . 2.9 The Q and CQ Opcodes 

The rest of the response-obtaining- opcodes are the most complex in 
the ^ VOCAL language, because a number of independent features m^y occur 
within their scope. The first of- these, the.Q opcode, is : the basic 
answer 'command. The syntax of the Q opcode is:.. 

/ . (Q <tag> <action> <tag> <action> ^. . • . ) ^ / 

As an, example of the operation of suppose we ha^Je the following:^ 



(Q INIT #(S ^'What is the first letter of the alphabet?") 

(T "Type the letted indicating your answer. "» 

. ; A (ANs/'A") \ ' ^ . ; " 

V HINTL ((S "The letter befo^>e B") (S. "Think harder")) * 



Section 2*9. \ ^ , . ^' 'v . The Q and CQ Opcocies 

(s "Good|') ; ' . • 0: I 

WA , (S "No, the answer is A")) - - 

Ih the abov4,^ the tag^ A, CA, WA, and HINT are- iised to label ^ the 
action -conponeat that follows the tag* 'j?The example is interpreted 'as_ 
follows: First, the sentence . ''What is the first " letter- of the 
alphabet?" is spoken,-" and will be repealed each time^ the student Xy?^s 
(JTRL-n^A^^-Next^ .the' sentence "Type the letter indicating your ^swer" is 
printe^^ on the '^ermitial, followed by a -second line beginning With- 
Tl^$ program will' then -pause until the student type&^5omething» If the 
student types CTRL-H he is told "The ^letter before B'*^ if he types C^RL-. 
H ag^ain (any jiumber of times> he -is told "Think harder" (each timeX* If. 
hie types the letter . "A" he is told "Gpod" ^n^.-the exercise, is en^ed* If 
he types anything, else, he is ,told "No, - the answer is A*S^ and- the; 
exercise is ended, since no R tag is ^ given- (i.e., no repeats' are 
specified—see Section, 9* I) • * _ 

The CQ (Cascac^g -Questions) opcode mi^es it easy to^ code exercises 
that ask* one question, then ask another if the first is wrong, then 
anotTier, etc. The ; components of each list in the CO opcode can be any 
of the"^ tags described in Section 2. 9;1. ^ , ^ • 

.(CQ (<list of' tags and actions>) , ' ' 

(<list of tags and actions>) - * 

Each <list of tags and actions> is a separate question and has exactly 
the same format as described for the Q opcode with the sole differen^ce 
that the Q is omitted at* the beginning of the list^ Questions are given 
tintil one is correct, or the list pf exercises is exhausted. , ^ 



2«9.1 Tags for the Q and CQ Opcodes ^ - 

The following ^ags are availab^Ie for" the answer-obtaining opcodes: 

1. 4nIT ( <againa^tion> . <promptaction> )• 
<Againaction> is executed upon first entering, the 
exercise (and repeated for CTRL-A" until a ^^ppnse is > 

i matched). - It is either a single action oir^a . list of ; 
{ action^. <Promptaction> is executed whenever input f rOm ■ 
the student is requested. The defaults for these ^ 
actions ^re to dio nothing. It is reconmended that the : 
full discussion y<5f tfie exercise at hand be included in,- 
the <againaction> and a brief description of the type of 
input requested be included in the <promptaction>, e.g*, 
■ (T "Answer Y or N"). ^ 

2. - A <answeranalysis opcQde>. Analyzes the answer. 
The answer-analysis code . following this tag specif ies 
the correct answer. , * ' 

3. CA <action>. The action to perform if the 
answer is correct; this also finishes the Q^ opcode. ^ The 
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default is to- say that the student's answer i§ correct, 
using 'ja randomly selected corris|t-answer response^ In 
• other w^rds, ifi? the author jdoes not specify an action, 
the program will answer with "good"" or "excellent" or 
some othejr appropriate response. sThis ^^respeipse is 
selected at random from a list stored by the program. 

4. -GAS ('<cbrrectaiialysis> kackion> XCprrect 
Answer Select^JT. This 4.s *a list ot\ pairs ^ of answer- 
analysis opcodes and ' actions witii the>^ interpretation 
that the first;, pf the <correctanalysisi> opcodes that 
^causes" a match Vill cause^the corresponding <action> to 
be ^performed; the exercise vill be considered correct^ 

. 5. WA. <actio'n>* Actio^i to take if '^the ' answer is 
wrong; .this finishes the opcode if no. repeats were 
speci3Eied» The default is to say that the answer^ is 
^ wron^ using a randomly selected response-^ / v ' 

■ " • " ■' ^ \.. 

_ 6l 'WAL ( <action> <action> This is a list 

of actions to be given -one at a time, each^ time the 
.student gives a wrong respo^e, until the last item in 
the list. The last <actia^ in the list w±ll then be 
" treated just like the <action> following' a simple WA. 
That is, the ^question will be furthur repeated^ the 
nun^er of times specified by the "R" opcode, or until a 
correct answer is given. Each wrong answer will cause 
the "last <action:> in the list to be given until , the last 
repeat of the question when the FAIL actions ^ill be 
executed^ if th,ey have been coded. - 

7. WAS C<wrongaTialysis> <action> ...) (Wrong Answer 

" Select) • ^ .This is a list of pairs o£ answer-analysis ^ 
opcodes and actions with the Interpretation that the 
first of the <wronganalysis> opcodes that causes a xaatc^ 
will cause the corresponding <actlon> to be performed. 
In any case, the exercise is considered j^rong, s incest 
is assumed that any CA or CAS has already been executed. 
The purpose of this tag is to catch specific wrong 
answers. ' 

♦ , '-' . ♦ 

8. R n. Here, "n" is the niimber of times to ask 
for an answer, and is defaulted to 1.^ For example, R 2 
would mean to ask the question, and then repeat once 
if it is answered wrong the first time. 

9. FAIII <actipB>^ Tliis specifies the action to 
take at the end i^Ixen^ the student has^failed, in R tries, 

% to answer , the qu^^stion correctly." ,It is ^useful for. 

. exercises that contain -an R, since FAIL can be used to 
inform the student of the correct answer. Jt is an 
error to' use the FAIL opcode when ^nly one attempt is 
allowed. In other words, when using FAIL ^ there should 
also be an R n f or some .n greater than 1. ^ . ^. 



Section 2.9.1 - / Tags .for the Q and<;^ Opcodes 
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"■ 10* HINT <action>. "This is the* hint, to* givc-^ the 
student if he ^ks for one^ The default i^ -to say that 
no hint is available* * » * , 

• • - • . '■ , -r ■ /■ • \ ". " 

^ !!• HINTL C. <action> <a£tion> •/i ' y This. is . a * ^ : 
list of hints to ^be, given,., one \ each . time . CTRL-]|^ ^.s * ■ 
typed; the Tast <action> in^the list will be repeated as ^ 
often as requested.. . - . " 

, - 12. COMMENT- ( <anything> ). Whatever is within the 

scope of t*he immediately following setT of g^antbeses is 
'^ignored, ^though • Quote marks- and parentheses -must be ^ 
- . - properly paired so that^ VoCAL can detect the end of the 
; J ' cooament- Note that ' in this construction, COMMENT is ' . 
. used, as a TAG, not as the CAR of a list. 

/ . These tags *and^ their .corresponding actions -may ^occiir in any order. 
'Either an .A ar a CAS tag must occur; but all other /ags are optional. 
It is an error for a tag (exciept C0I4MENT) to occur'.more than once in an 
answer-fetching opcode.^ - Some of : the' combinations: are illegal* For 
'^example CA and CAS should not oc.cur ' within the s^ope of the same Q 
opcode. Also, at most one of the i^rong answer tags (WA, WAL, WAS) may 
be included in the scope, "of a Q opcode*. * , : - S \ 



. 2.9.2 Answer Analysis Opcodes . ' ' 

•. ■ ■ jfk' • . . " - 

Once a response (answer) is obtained from the student by th*e use of 

tHe Q or CQ opcodes, it must be checked. ' This is .done*-by the answer- 
analysis opcodes . The analysis is dgne by testing' . whether tixei^ is a 
match between what, the student has typed and the coded answer (s).. ^ 

. For example, the command: ■ ^ * . .. 

»^ ■ . ■ . 

(Q A\(ANS :'74"))\^ ^ ' 

gets a response from the student, and then analyzes it by comparing .for 
exact stiring equality with "74" for correctness. . (In this example, the. 
other parts, of the Q opcode are omitted, thus , default ed. ) Except for 
TRANS, all of these opcodes are quite simple and standard. 

Several kinds, of editing are done by these opcode^ on the responses 
that the stiia^t types ^ All'^ of the opcodes remove beginning and 
trailing spaces and tabs, and all of them compress . multiple spaces an^" 
tabs to a single space. These procedures are called space compaction . 
Additionally, most opcodes convert lower to upper /-case*, called upper 
conversion . "A few opcodes that are prepared to accept several Answers 
will scan for those answers separated by spaces or commas. This is 
called word scanning .. . * ■ . 

- The student's input ;Ls referred to as <response>, below. 

/ (ANS <sequence of st;rings>) • " 
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.« • " ■ > * * . ' ' - ' 

After' space^ compaction and upper conversion of <re3ponse>, ANS checks to 
see^ if - any\string in '<sequence of sxrings>. is exactly the samfe as 
<response>., *In o<:her vords, the stildent must type exactly one item from 
the sequence for a match to Z>Ccurl * 



*^ ' ■ (ALJaANS .<sequence of strings>) " . \r \ 

^ ■■■■■ • ^ • - • / V- . ^ ' 

Af ter space ^ compaction, /*"upper conversion, and word scanning of 

<response>, , ALLANS makes certain that all. of. .the stringscin <sequence of 

strings>; were typed by -the student', and that no additional strings were 

.typed. . So the, student will have t(\ type in all, and only^ the. items in 

the sequence, but in -any order, ' / 

\ ^ (ANYANS <sequence of strings>) . 

After space compaction, upper conversion, and word . scanning " of 
<re^pnse>, if any <string> in <list pf strings> matches any word^of the 
student's <response>, then a match occurs^ Thus, if 'the student types 
an item fro^ the sequence, the answer will he counted as- correct eveii if 
h€ or she typed additional words before or after it. ' -^^ 

(EXACTANS <sequence of strings>) \ , 

^ - ' ' • " • " ■ - 

this is likfe ANS except that upper conversion is not performed. 

^ (AFFIRM) , . . • ' 

Some "tfue"-like response miist be given (c^ase ignored): Y YES TRUE T. 

. (NEGATE) ' - 

Some "false"-like response must be given (case, ignored) : N NO FALSE F. 

' - ' ■ 

. • ' ' (TRAILS <list of strings>) 

. ■ ■ ' ■ / ■ 

This opcode relates specifically to the logic course and other 
mathematically based courses. Each "string" iiji" the <list of strings> is 
parsed' into, an internal expression (by the compiler); the student must 
then type something that , ^ when \parsed, is VEQUAL to. the parsed 
expression (VEQUAL is a function in the. logic- and set-theory-based 
programs.) ^ / ' ^ 

' ■ - (MATCHANY) ' - ■ 

MATCHANY is an, opcode that matches .any non-null 'answer vAatsoeveri It 
is useful for the logic of some of the opcodes such as CAS and WAS. For^ 
example^ in the following Q opcode Jthe author traps two specific wrong- 
answers, responding appropriately to each. For any other wrong answer, 
the program simply replies by typing 'Vrong" on the terminal: - 

• ^ ' ■' ■ - ' . 

. (Q A • ' (ANS •74"0 

WAS • UANS "73") (S "One too few.") ' . 

(ANS "75") (S "One too. many.") 
(MATCHANY) -(T "Wrong."))) 



.Section 2*10 * Cojiditional Op^cod'es 

•2.10 Conditional (facQdes ^ >■ 

' .. J A number of j opcodes check a condition in the driyei^*to decidja 
whether or n^t /to , execute, the statements contained therein; - For 
'"example,, one wants to do something differently depending on Aether or 
not audio is available. . . 



(AUDIO <actioris>) ' 

This executes <actions> if ^ audio is available and selected. ^ * \. 

> ^ ^ (DPY <actions>)-^ * - • 

This executes <actions> if , a:udio is -not available or if it was not 
selected, provided the student is using a display terminal. ' It is an 
error to include any audio-class opcode within the scope of a DPY. 

' • / ^ _ . ^ . ■ . 

• ' ' (TTY ^ctions>) 

This executes <actions> if the student is using a nondisplay terminal. 
Both audio- and display-class opcodes are illegal. ^ 

(NONAUDIO <actions>) 

This executes <actions> if audio is not available or npt selected. It 
is an' error to include": an audio-class, opcode within the scope of a 
NOiJAUDIO opcode. And since, the intent of the NONAUDIO opcode 'is to 
s»pr|^rant both -Me DPY, and TTY opcodes , display-class opcodes should not 
• be 1ased either* Also, tljis opcode should not occur in the same exercise 
dn which- the DPY or.-TTY opcode is used. * 



.2.11 Branching .Opirodiss^^ -^' 

' " • 

(GOTO <Iessonfiumher>"><:exercisenumber>) . . * 

This goes . to <lessonnumbJer>*<cexercxsenumber> in the course. If 
<exercisenumber>. is empty, ^ then 1 is assumed. This changes the 
student's place in the course.' 

(CALL <lessonnumber> <exercisenumber>,) 

This interprets an exercise for the student, but does not require any 
answers from h±m* The student may not log out from that lesson, but 
must return to 'the current "lesson. exercise" before continuation is 
allowed. ' * 

' ' (CHOICELESSON <lessonnumberlist>) ' 

This gives the student a choice of which lesson he wants to do next. 



(BRANCBLESSON "text" <lessonnumber>) 
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The ^text' will be t;^ped in the scroll regiou, then if the st-udent has 
answered 75 percent' of the Q-typfe exercises in the current lesson 
correctly when BRANCHLESSON is encountered, he will be given * the choice 
of, doing ^he rest of exercises "iij the current lesson or skipping 

ahead to. <l*essonnumber>; if he has not answered 75 perce'nt correctly,, he 
must do f he remaining exercises • ^ 



, (RAND <action> ''<action> ...i. ) 



i9 



This' selects randomly' one action to- be^ Executed. For example, if . we 
have n <actions>s, -then a random number between 1 and n is generated, 
-^and the corresponding <action> is performed. 

\ ^ ' ' } >_ ■ ■ ... 

NOTE: RAND is;c:generally used to select <a derivation for the student, 
to doy If the' student iSgs out in the middle of such an exercise, then 
his work is saved. The next time he logs back in, he must get the same 
exercise.- So the randomly selected options picked by the driver are 
executed in the same order on subsequent logins- ■ 



2.12 \ HELPMQDULE Opcode 

The HELPMODULE opcode has the syatfai^tic form: ^ ' 

(HELPMODULE <nunber> '"description*^ <graph info> <actions>) ' 

where <number> is t^e number of this help module; "description" is a 
one-line description of. thi|^ help module, to appear at the top of the 
display screen when Xhe ^actiens are interpretedJL. <graph info> is a list 
of information, needed by\the help system; and <actions> is a sequence of 
VOCAL actions for this help\module. ' . ^ 

There are' three types of information which nay be placed in the 
<graph info> list. The first two " are mandatory, the last not. - They 
are: " ' ■ . 

(NAME "name of the help module")' ^ ' 

(DESC "description' of what the help module covers") 
. V * (EMPH ■(<H> <L2>) (<L3> <L4>)^ ...•.(<L2n-l> <L2n>)) \ 

Both the NAME and BESC opcodes facilitate the student ''s accessing of a 
help module, and are used in offering the choice of available topics. 
The graph info description nay be the same, as that which is used as a 
display, header, or it may be different. The- optional EMPH opcode 
specifies lessons in which the help module is to be emphasized. Each Li 
which occurs within the scope ^ of the EMPH opcode is an integer 
corresponding to a lesson number. These should appear in ascending 
numeric order. See Section 4 for details' of .-^ the semantics and a 
description of the help System, Z' ^ - 



Section 2.13 ' • Flag-alteration Opcodes 

. ' '<i . * ' . ' ^ 

• " ■ ■ 

2. 13 ' Flag-alteration Opcodes ' ^ ^ 

^. •The following opcode's set varipiis entries in the student histojry 
file or in the proof checker, and ccfatrol the ruti-tiiae operation^o^ the 
driver. The actual, theories and history entries axe discussed in 
coij£se-specif ic supplements available to lesson authors. 

^ \ - • (CONNECT J'theoryname") - ' . 

This^ selects: the context theory (including parser, grammar, axioms, 
definitions, a^d theorems) 'Tfo'r derivations and student response under 
the Q and CQ ojpcodes. . 

; (INTERPCONNECX "theoryname") 

This . selects the context theory (including parser, grammar, axioms, 
definitions and theorems)' for interpretation-type exercises. 

(WANTIDATA "truth value") 
' ' •'■■^ 

This flags the student for collection of data, e.g., connect time, 
resf)onses, etc. "Truth value" in this and the following opcodes must be 
:either "TRUE""or "FALSE"; that is, "T" and. "F" are^not siifficient. 

(LINE! INFO "truth value") 

This selects format;, for -printing proofs during execution of a derive- 
class oi3code_ ("FALSE" suppresses printing of flagging, dependencies, 
etc.). V . 

. > (SHARPIFLAG "truth Value") 

This selects form for ambiguous names during execution of a derive-class 
opcode. Value = FALSE requires the student* to use ambiguous names of 
the form #<integer> in existential specifications. , Value = TRUE allows 
•the student to use any legitimate variable name. 

(ERROR'MSGS "truth value") . 

Value = TRUE causes terror messages concerning quantifier rules to be 
printed after the studtent enters a line containing spch an error; value 
FALSE supresses quantifier error messages and causes the student to be 
informed at the completion of the proof that it is incorrect due to a 
quantifier rule error. \ * 

The following opcodes allow " changes to arbitrary history lists. 
The first* element of a history list is the name . of some set, and the. 
remaining elements of the list are the members of that set. 

(SET "historyname'V ("item" "item" ...^)) ' ' . 

' .. . ■ ' * " . ' ■ ' . \ 

If there: 'is 3" historj^list yith the name ""hi^toryname', SET changes .its 
value; otherwise SET -creates a new history list of the form (historyname , 
ite& item • . . ) • ^ . " . ; 
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V ■ (ADD "historyname",C"item" "item" ... )) ^ 

This\adds it^ems to the set of iteins in the list with name ^historyname'. 

CREMOVEX^istorynaiae" ("item" "iteia" )) 

This removes /items from the set of items in'^the- list with name 
liistorynamer. If an "item" mentioned is not on the- list, it is. 
ignored* To/ remove all the items from a list, (SET "historyname" ()) is 
bette;: tha^ using REMOVEv ' ^ ■ ' / ' • 

* "■' ,u 1 ■ ■ ■ ' ' ' . . . , _ " ; ■ . 

' 2.14 DERIVE -class Opcodes 

• ■ - . ' * • . • ■ 

The following opcodes /all specify • some sort of call on the 
derivation machinery. Their interpretation is* done by the proof checker 
and" is discussed in course-specific supplements available to lesson 
authors.. . * 

(DERXVE "goal" <tag> <:action> <tag> <action> ... ) 

"Goal" is thje string representation of a formula to be derived^ " This is 
a required argument and' must immediately follow the ^opcode. The other 
arguments "to DERIVE consist of pairs of <tags> and <actionsC^, all of 
which may be defaulted and may occur in any order. / 

> 

1. . INIT <act''ions>. These actions will be done when 
the DERIVE op<:ode is begun. If the DERIVE opcode > i^jpot 
within t}iB scope of a TEM or TEM2, the <actions> can be 
replaced by a TEM or TEM2. * • . 

" ■ " ' " '• "5 

- 2. PpML ( "premise" "premise" ...)^ This is a 

list of string representations of the -premises. " - 

' . . ■ ' y 

, . 3. HINT <action>% If a hint is requested by CTRL- / 

H, then <action>, will .be executed. . • * ' . " ? 

4. HINTL (<action> <action> V* )• Whenever CTRL-^H 
is typed, the next <acl:ion> is executed (the last% is 
repeated as of ten; as requested)'* 

5. RESTL <restrictionlist>. ' This is the" ^> list of , 
restrictions on the rules of inference, etc. , that 'the ' 
Student must or. must not use in thia derivation. - 



6. DONE <doneaction>. ' When' • the proof - has beeri' 
•completed, <doneactiqn> is executed- . ■ ■ 

Other opcode^ with the same syntax as* -th^ abov^ arerc . 

1^ INTERP. The student is • asked to provide ap 
" interpretation (in the connected interpretation-^ theory) 
of the premises^^ in PREML and the. conclusion- in. "goal"* 



Section 2.i4 V DERIVE-class Opcodes 

Then the student - is asked ^ to' ^ch'eck' his oaf - her 
Interpretation by deriving the interpreted premises, and 
the negation of the interpreted conclusion in the 




^ ' 2. INTERC. This is . similiir to INTERP,' but the; 

; ■ ■ ■ student is. asked to .show ^'thsct the premises and 

^ . conclusion are consistent* ;, 

/ /3.^ DI. The student is asked to decide whether to " 
^' ^ do' an: interpretation, or -a derivation. If the f ormer is 

chosen, the driver ' interprets this opcode as a DERIVE; 
if the latter is chosen, the opcode is interpreted as 
/• / INTERP. The student may restart the exercise and change 
his or her choice^ 

> ' 4. Die. This is like DI except the choice is 

between INTERC and DERIVE (where the student is asked to . 
derive the negation of "goal" if he chooses' to do a 
" ' derivation). 

(SYMB "formula;* HINT <hintacti9n> "goal" <tag> <actio.n> ...). 

The SYMB opcode first requires the student to symbolize the "formula" 
• (\Aich can also be^a list of formulas, ("formula" "formula" v ), in 
which case he must symbolize all of the formulas). If he requests a 
hint -at this stage by typing CTRL-H, <hintactipas> will be- executed- 
;The HINTL tag can be cod^d, with the. usual interpretation. If the 
student does the symbolization correctly, the exercise is ended; if not^ 
he is given the choice of trying again or doing a derivation. If he - 
.''chooses the latter, the DERIVE opcode is invoked with the "goal" and 
y list of tags and actions coded in the SYMB opcode. 

(TA "formula" (<atomic> "value") (<atomic> "value") ..•) ' 

V- >^yaiue' is, a truth value (either T or F}:^ and^x:atomic> is an atomic 
sentence of the current theory • TA r^qgife^^"^. student to determine 
the truth value of ""formula', given the. values, for the atomic sentences 
of the 'formula. This opcode is generally used only within the scope of 
the ^TTY opcode^ where the display capabilities for conveniently 
• presenting and dynamically altering truth tables are absent. \- 

- : ' ■ ■■■■ ■ .■■ ■ : \ 

V <CEX "goal" <tag> <actions> 5tag> <actions> ...) s , ' 

• ' - ,".-.> 

^ Here, the syntax is the same as in DERIVE; it asks : student to provide a ' 
sentential cojanterexample by. choosing truth values for atomic sentences" 
th^t will mak^ the truth values of the premises true, this "truth value of 
^goalS^, false, and then proceeds iii each case as in TA, to check if. he 
has succeeded. 

^ • . . (BC "formula") 

A ' - • . 

This is like DI, except the student chooses between doing a derivation 
(DERIVE) or a sentential counterexample (CEX) . 



ERIC 



VOCAL Manual / , . . v Octol^er 19, 1977 

, . ■ . ■ - ^ . * . ■ 

It 'is an error to have more tH^an one derive-class opcode in the 
same' .exercise unless all of them occur within "-^the scope of '-^a MENU . 
opcode* ' ^ . ' 

- 2. IS MgNU Opcode - . . V _ , ' 

--(MENU <cf^iterion> INIT <actions> DONE <actions> .<entree> <entree> •i. ) - " 

The MENU opcode is designed to provide the lesson author a^" means of-; 
presenting a set of derivations or other derive-class exercises for the ' - 
student to work on. The student is allowed to select the order ' of 
exercises, -and need not complete , all^ of them. Work on partially 
completed derivations is saved. The <criterion> is the number of . 
entrees the student must complete before going on to the n^xt exercise. • 
INIT <actions> are actions to be performed when the student begins- the 
menu (and repeated when he logs in after logging out while in a menu). ^ 
The- <actions> may be 'replaced • by a TEM or TEM2 if . desired. 
! DONE <act ions > are performed when the criterion is met by the student 
(i.e., he has 'completed <criterion>' number of the entrees). 

Each <entree> has the form: . ^ • . -• 

• ' . ■ > • ■ . ' 

^ (ENKIEE "description" <action>) 

■ ' ■ . * -* > . ■ . • ' 

The "description^' is a one-line string which will appear in the MENU, 
and <action> is' the exercise for the* ENTREE* The <action> ^is generally 
a derive-class opcode, although it may also be a TEM or a TEM2 which 
contains *a dferive-class opcode. Tt ^s an error* to include .a Q-class 
* opcode in anr ENTREE. * ' ^ 

; The^ action . of the MENU is as follows./ First, the INIT actions are 
•performed. Next, a "menu" is displayed which consists of an identifying 
. number for eacH ENTREE, the string "description" for it, and an 
indication of whether the ENTREE is completed, partially 'completed^ or - 
not begun. Also the criterion will be displayed, with an indication of 
how much remains to be done. .The student then selects " which ENTREE he 
wants to work on and the <actions> for That ENTREE are performed;^ When 
he finishes (or decides not to do any more, work on that ENTREE) the IffiNU 
is displayed again. When the criterion is^ met, the DONE actions are 
performed -and the student is then given the choice of^ selecting more 
"ENTREES (if any remain) or of going on to the next exercise. v ^ 

It -is' an error to have more than one menu in a given exercise. 

■ ■ . / . ■ • 

. i ■ ' . • 

^ 2.16 Compiler-specific Opcodes 

■ . The following opcodes affect only the operation of the compiler and 
are "swallowed". by it. 

. . - . > ■ ■ - • ■ ■ /. 

. (COMtlENT "anything") 




Section 2,16 ' - ^ Compiler-specific Opcodes 

The above is a comment, -at any point it occurs,' and is ignored by the 
VOCAL compiler. ' \ 

. - ^1 (COMEILECONNECT- ''t:heoryaame") - 1 

This opijrode , tells the compiler to start using "theoryname" as the 
context theory (including parsj^r and graiMiar) for compiling formulas in 
the scope of derive-class, or TRANS, ;opcodes* 

^ (TEMCHAR "character") 

ReWets the character" used for the templates to the first character of 
the storing "character". The default character is "%". * 



\ 3 • Browse Mode - 

•There is a feature available in all VOCAL-based courses called 
Browse Mode, which allows the atudent to review old exercises or to lopk 
ahead, in the curriculum* Browse Mode is entered^ by typing a CTRL-B. 
The program will reply by typing 'the following summary of the Browse 
commands: , " ^ • ' 

**** BROWSE' MODE S * ' ' 



Type one of the following: 



D n Describe Legfeon ^^n' ' - 

n List directory of , Lesson '^n'' 

7S XL. Show Exercise ""n' in this Lesson . 
.S l.n Show Exercise "^n' in Lesson "^l' . - 
I* Index of Saved Proofs • . • \ . 

R l.n.e Review Proof (lesson. exercise* entree) 
E l.n.e Erase Proof (lesson- exercise. Entree) 

"""Z Re-turn tc your exercise. ' . - 

Here is an explanation of those commands: . ^ - 

D n . Describe- Lesson number n. Each^ lesson has a brief 
discussion describing the, material it covers. .This will.be 
the <actions> taken from the LESSON opcode (see p^ 4). 

L n List the lesson directory for Lesson n." Recall that 'each 

. exercise begins with a brief one-line description of itself 

(th^ "description" string from the EXERCISE opcode, p.^ 4). 
' 'The L command presents all of these at once for. the lesson 
specif ied*^. . 



^I, R, and E are specif ic to the logic; course and' may or. may not be 
available in^ other, courses. , ■ / ' ^ . . \ 
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S n Show exercise number n in the CURRENT- lesson the 

^. . - : • lesson ' the student was in when he» 'entered Browse Mode). 
\ ^ ^ S ' This allows him to look at ^ the exercise just as if he were 
_„„working --it^--i:XC£EL" -that. -any^ 

CQ^ or derive-class opcode * (including MENU) will not be 
executed. ^ . . ' ; 

S n^l Show exercise n in Ifsson 1. This is just like the other 

. ' version of Show, Except that it allows the stuclent to look 
at an exercise in a lesson other than the current one. 

I -Index of Saved Proofs. There is a facility available that 

allows the student to save proofs/ ao that he can look at' 
; ' them again later. To find out what he has saved, ^he 

"Student goes to Browse Mode and types This gives him a,- 

■ directory of the available proofs. 

R l^n.e Review Proof (lesson.exerclse. entree) . Onqe the student 
knows the number of the propf he wishes to look at, he uses 
the R command to actually see the saved proof. 

. ^ ,^ ■ ■ ' ^ ; ■■ . 

E l.n.e Erase Proof (lesson. exercise. entree) . The student is 
allowed to store only about 25 proofs for l^ter reference. 
Once he has reached the limit; he 'is not allowed to add a 
, new proof unless he deletes an old dne first.' The Erase 

Proof Command allows him to. do this.' 

CTRL-Z Leave Browse Mode. This returns ^he student to '' the lesson 

and exercise he started from. The program saves^ a copy of 
• - his "chalkboatd" area and will restore it to What it was 

> ' just before he entered Broyse Mode; the "scratch-paci" area 

V * is lost. . . 

Browse Mode makes it easy for the the student to review something 
earlier in the course, or if he is'the kind of person who likes to look 
ahead in a book, he can do the on-line equivalent. This feature is 
especially important in courses where the curriculum material is 
presented at display terminals instead of in textbook format off-line or 
in classroom lectures. Notice that other than writing the description 
strings /and the- <actions> for the LESSON opcode, authors need not make 
any special effort. It is taken care of automatically by the VOCAL 
compiler and the course driver. 



The Hel 




A help-system facility is available for use with all VOCAL-based 
courses. It can be used to create and maintain a help system for the 
course. This section explains the structure; such sysrems should have, 
and how to implement them. * . 



Section 4^1 . . Description 

• , • - ■ ■ ■ ■ • - ■ . ^ ^ '. 

4«1 Description ^ * 

\ ' . • , 

The student invokes the help system typing ' '"HELP"' to the course 
—driver •—When -he enters the -help - system -he has-- two^ ways- of accessing 
inforpation: by naming the topic on which he needs help, or by being 

* questioned by the computer* 

The computer queries the student by means of a topic decision graph 
whjLch is us4d to preisent him with a selection of topics to choose among. 
The particular question - or '^interrogation*' structure used by the 
computer is determined by, the author • However, two' factors can cause 
additional options to be added to the initial topic choice presented. A 
relevant help topic will be placed 'at. the^head of the topic list if the 
program is. currently in some. error mode, or if the author has specified 
that. the topic should lie emphasized within the student's current lesson. 
Thus a syntactic erpor. in an input string might cause a help module on 
syntax to be emphasized* And in the early lessons- of a course^ it might 
be desirable to place emphasis on the help system itself • 

The folloj^ing gives an example of how a choice might typically be 
presented to the student: 

Type for help on 

TA [TA] TA duties, hours, etc. 

RULES [R] Rules of inference 

CONCEPTS [COUfC] Basic concepts of ^ the coihrse . i 

ADMIN [AD] * Administrative matters 

GRIBE [GRI] " How to send a suggestion or complaint , 

* <student inputs choice here> 

The 'characters in square brackets give the shortest sequence ' of 
characters the student can type and have his request properly, 
recognized. But he is not forced to choose one of the options 
explicitly displayed before him; he can, if he wishes, enter the name of 
any • help module available, provided he , knows it* The choices are 
presented in case he does not know the name of the suitable topic. 

" Some ^topics will have associated VOCAL code to berpresented^as help 
to the .student. .Other topics exist only to guide the interrogation, 
process, and have no VOCAL actions written for them. For example, the 
help system might present the RULES option, only to give the student a 
chance to find out the names of the help modules descrlrtdLng the various 
rules of inference. - )• r 

. If VOCAL code for a chosen topic, is written, the help system first 
fetches . the corresponding HELPMODULE and . interprets the VOCAL* code in 
it.^^. The^ student is then presented with another list of options. If 
the last chosen— topic has further topics associated with it in the 



.. ' ^°If the student finishes typring in a topic name with a CTRL-Z, 
only the -the associated topic list is typed out. This allows a student 
who has already seen/heard the VOCAL code to skip over it. 
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graph, the choice list will consist of these topics, otheirwise it will 
be the initial list. "The student may then' either exit from the help 
. .system (y\±a CTRL-Z), choose another topic,' • or return to ' the initial 
.__._.-interrpgai:ion_ by entering . the null_ response , i.e. , th^^ 

The interrogation^^procedure should be regarded as a graph rather 
than a& a decision tree.^In many cases it is natural to use a topic- 
subtoj^c structure. But the author may also want t9 remind the Student 
' of related topics,. Thus a module discussing thev. concept of tautology 
'*^mght h^ve- modules, on consistency and inconsistency as associated 
topics. It Is 'also easy and often useful to define loops in the 
interrogation structure.. This will become -cleayer in examples' to 
■follow. • . V ' - ^ ^ 



'4.2 '\ Defining a Help System 



i _ ■ ■ ■ - ■ : ■ 

'. It. is necessary to H^ite a series of files that contain the 
■ information to' be made available via the help system. If the help, 
system is intended to of f er inf orinatlou on teaching assistant hours, 
rules of inference, and tautologies, corresponding help modules mus,t be 
written in these files: All the help actually given to students is 
taken from them. 

These file& are written in VOjCAL, where each; entry is* within the 
scope of a HELPMODULE opcode (see p. 19) • Except for the ..inclusion .of 
the special tags NAME, DESC, and EMPH, each entry looks just like an 
ordinary ' exercise, with the EXERCISE opcode replaced by the HELPMODULE 
opcode. The help system files, cannot contain the opcodes^ L]?SSON or 
EXERCISE, but they can contain questions and derivations * designed to 
help a .student understand the topic The student's performance on these 
questions will not affect the ^score' which is recorded for -control of 
BRANCHLESSON. _ f 

A special file needs to be written to define the interrogation 
structure used by the computer. , This file will contain a graph which is 
usually easily written and which is easy to alter if experienfte suggests 
that another choice sequence is more appropriate. The Kelp system 
compilej: is then run to/ put all this., inf ormat ion dn a form acceptable to 
-the course', drxvep: ■v-* ^ ■ -- v-.- . ^. 

4.2.1 ' The- 'Help Hddule Files " ; 

■ ^ — ~. — ■ — ' — ' ^ ■ ^ ■ .-■ i ' ■ ■ ■ •• •■ ■ ■ 

The help modules may be included dn onfe or more 'files. The source 
files may be named . as desireci, .though they should have a .VOC 

extension for ease in operating the i VOCAL , compiler. X^cK such file 
" c^ontains a sequence of HELPMODULE opcodes . , They . furnish inf oirmation 
used in the interrogation, and provide the VOCAL code to be interpreted 
if help on a particular' topic is requested by the student. The 
helpmodul^ files must, be .processed - by the VOCAL compiler, . and., the 
resulting .VAL files submitted to the help system compiler.^ - 



Section 4. 2.1 The Help Module Files 

If differeat help systems are being defined for several, courses^ 
they may share some of the same" helpmodules- Help on the use of Browse 
Mode, for example^^ would probably be the same for all courses.. For this 
: ..reason,., the .♦VAX., f iles f or ..helpmodules , unlike _ those_f or _lesspns_,^;dq_.nqt^ 
have to be on the curriculum directory. ' The HELP. PRC file which 'is 
create4 for leach course by the help system compiler informs the driver 
of the directory and file naihe on which the helpmodule for each; topic 
defined in the graph may be found.. A help system does not have to use 
aill the^ helpmodules on any file which it accesses- Different ^courses 
may '^pick and choose' among the various modules on a given file. If, 
however, the same topic ^niame is to be used with different help 
information in different courses, separate helpmodule files must be 
created for those top^« whose, definitions Arary from couFse to course. 
This might occur, for example, in writing helpmodules on inference rule's 
which have the same aames for each course, but use different derivation 
examples in the theory appropriate to the course'. ' • 

The ' syntax and semantics of the HELPMODULE command (p. 19) should 
be clear, with the possible exception of the .optional EMPH opcode. This 
is irsed to indicate the lessons in wKich the help module needs to be 
emphasized , in the sense of being placed at £hiB head of the topics in the 
initial interrogation of the student • / ^ 

To illustrate this, suppose that it is desired to define a help 
module about some derivation command, e.g. ,> Tautology. Suppose in 
addition that this rule of inference is introduced in Lesson 76 and that 
exercises in Lesson 105 are particularlaf suitable for its .application. 
One might then write the following help module: 

[HELPMODULE 3 "TAUTOLOGY: Using the Tautology Rule" 
((NAME "TAUTOLOGY") ; 
- ^ (DESC "Using the Tautology Rule")-. 

(EMPH (76 78) (105 105))) 
[AUDIO 

- (S "Just type '^T' to use the Tautology Rule")] ] 

Here the help available on the^ Tautology Rule would be emphasized in 
Lessons: 76 through 78, and 105. ^ 

■ . ■ , ' ' .... 

If a helpmodule is to be., accessed by more than one course, the EMPH 
list -may contain numbers from each of ■ these courses.. For^' 

example, if there are three cpurses, whose lesson numbers range 
respectively in the lOO's, 200's, and 300's, then a topic which is to be 
emphasized in the beginning lessons of each course might have the EMPH 
list: (EMPH (Idl 102) (201.^02) (301 302)). 

■ ■ • . . . . ■ c . 

- If EMPH strings are declared for-^^ny help modules, the help system 
compile^r will produce a listing of the.. emphasized topics by lesson. 

s ■ ' . ■ * ' 

j:ij£- j.j^^ les son numbers, ..|or two courses are the same, . and^a 
helpmodule is to be einphasized la differejit 'lesspus in , .these courses, /it ^ 
Will be necessary to make separate 'versions* of 'the?, helpmodule wxth 
different EMPH lists. - - ; \ 
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J • ' ' ■ " 

Consistent\with the- rest of the VOCAL language, the. help modules in 

'any file must ^je numbered in increasing oi?<der, . from 1 onward* 

Furthermore, the length of module^ NAMES should be 11 characters or less. 

Longer _ strings,, willLdisorder the display„_output , althou 

Similarly, the length of DESC strings should not exceed 46 characters. 

The length of the help module names is not critical apart from aesthetic 

considerations,, since optimal topic name recognition is. done' 

automati^p^lly . ^ 

The help system compiler does extensive errot checking, and gives 
suitable warnings. . For example, the author will be warned if he doubly- 
def ines a help module topic or fails to define a HELFMODULE^ for a topic 
.declared' in the graph. Note ,that helpmodules must still be written for 
decision nodes which have no associated VOCAL actions, since. ^the 
helpmodule contains the description information (needed for ' thie 
interrogation d^isplay), and pos^sibly emphasis data. 

' . • ■ - ■ ■ ' 



4.2>i. The Graph File ^.v^ 



Only one file Is needed to define the interrogation structure for 
any' course. This ft^e should have the extension .GRAPH,- and may be on 
any directory. Whei? the":help system compiler is run, it looks on the 
connected directory for the graph file unless another directory is 
specified.. It also uses the name HELP.GR^PH as a default. The file 
should contain a single S-expressio.n, which is essentially a list of 
topic tiames and their subtopics. "The S-expression is . recursively 
defined as follows-: ' . ^ • • 

:= (<topic-list>) ' . 

!= <topic> <topic list> ( <null string> 

<topic name> | <topic name> <graph S-expr> 



graph S-expr 

topic-list 

topic 



The following is an example of what a help system list for an elementary- 
logic" course mi^ht . look like. It incorporates all " the above 
illustrations. . _ ' ; 

' . ITA - . . -.- ' . ■ 

RULES • ■ ' ' ■ ; ■• r 

: \ ■' ,V ■ .(BOOLE : 
• ■ J.-'. ^tautology;;:..; /\ ' -^-.^ ■ 

' HYPOTHESIS (ANTECEDENT) - .. • / . , '•• : " :-. 

■ . ; - ^ ■ ■ ' ' AA ■' ■ ■ "/ _\ ■' %: :' ■ •' 

■ CP (CONDITIONAL)) . '. ' \ \ . . • 

. CONCEPTS , « ■ ■ 

, (ANTECEDENT . - . ■. " 

CONSEQUENT 

TAUTOLOGIES • . ' ■ ' ' 

r (CONSISTENCY 

■ INCONSISTENCY) , "" . : . 

ALGOR'lTm-I ■ ■ 

CONDITIONAL (CP) ^ ' 

. .. CONSISTENCY . / 

- INCONSISTENCY^ - 
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*' • ' - * 

■ . ^ ADMIN 

/■■^ . ■ (TA • .. • ' . - 

. - ^ NEWS ^ \ ^ 

.„ L _1_ :j GRIFE 

. ;EXAM& 
. GRADg 
: GRIPEJ- -^ J ' 

The central id^a f^H^S^S^^fi^Wivip^^^^^^^ be displayed at the 

same'- interrogation are^-at"\he Jt'o^ the same list, and the topics • 

associated -y^th"^ a topic are/ contained -i,n a list immediately following 
the topic. Thus th^ f irst; .lievel^- of- interrogation in this particular^ 
help system would b^,betwe.eri TA, RUl^ES,^ CONCEPTS, ADMIN, and GRIPE, just 
as previc^sly 'illustrated A Further^ interrogation is defined by the 
sublists. So if _GRLPE is chosen, the -helpmocjule, as defined in the 
helpmodiile tile, is interpreted, telling the student- how to send 
'suggestions and complaints- to the course * authors; if RULES is chosen, 
the VOCAL c6de (if,^ny).'in the helpmoSule files is interpreted, ' and the 
further subtoplc lidt of- fopics is ^presented. ' — 

^ As previously ^remarked, the int^^rirogatipn need >not be a tree. In 

the above example there- are twap^ths 'to the same node for both the/ 
CONDITIONAL ""and t;he GRIPE hel^ modiiles. . In addition, there is. a cycle :^ 
If information on the CP rule is giVen,* the..student will be^ reminded of 
the help available on the concept of a conditional;- if this latter help 
module is interpreted, the student will then be reminded of the help on 
the CP^ rule. . ■ . r - ^ 



4.2.3 The Help System Compile>r • 

' . . When the files , containing the interrogation graph and the help 

' - ^ modules .have been, writ ten, the next^tep is '%o process them. One begins 
. by processing the HELPMODULE files using the VOCAL, compiler as described 
in tlie -next section. VOCAL will creat^e processed ver^ons .of the help ^ 
module 'fil^s>. These files will have a. .VAL extension, just as for lesson ^ 

■-. " files. . ■ ' ■ ^ , - - • ■ . ■ ^ :■. ..■ : ■ ■ 

. * ; The 'help system "is created by rim'ning the help system^^^;^^^ 

* \ called HELPMK- for "HELP syseem.MaKer'.. .,This-"program processes; t^^^ graph' 
; ^.'^ ^^ r * and help module files, producing .a cbrresponding ^un-time file, 

• ' 'bel^.^^ for; .usQ >y^the ;C^rric^um driyer..^^^ ^i^s s^lf -explanatory, in. . 

; - - . . 

V When one calls HELPMK, it first . presents the option of creating a 
new system- from scratch, or modifying an old one. If the Create option, 
is chosen, the graph file is first processed, and then helpmodule files 
. are processed until all the topics in the graph have been defined. 
Under this option,. when the compiler encounters a hellimodule- for a topic 
which"lias already been defined by an. earlier helpmodule, the second and ' v . 
subsequent definitions are ignored, and a warning is printed- the help r. 
systemvis, ready when the HELP. PRC file -has been ioved to the curriculum 
V •* ^ :.; -'v' " directory.-/- ' - ' • '■ ■ , 

i" ' t . ■ . • ■ _ . 

■ . ■■ ■ . V. ■■ . ■ ..... ■ ' . ■ ■ . • 

ERIC 35 . - - 



VOCAL Manual 



October IS^, l^fcs^ 



^ If a fatal' error occurs after the. graph file has been processed 
(for example, some module has. incomplete^^aph info), then the structure 
at that point * is dumped onto a file called HELP. INCOMPLETE .and "the 
_compilation_ls .aborted.. _.Th^ error . .may_ then . be^correc ted^^and HELt^UC^ r^^^ 
with the Modify option using HELP. INCOMPLETE as the "old' sy^m.^ 

If topic. emphases have been • declared, a further file, HELP. LESSON- 
EMPHASIS, is also created, giving a ' listing by lesson number of the 
emphasized topics. This will assist the author in keeping track of 
which topics are emphasized in which lessons. ' ^ » 

4.2.4 ' Modifying an Existing Help System 

If one wishes only* to' change the VOCAL actions in a, helpmbdule 
which is already defined in a working help system, it is sufficient to 
edit the source file and generate/ ^ new version of* the .VAL file (the*^ 
file name and directory must not be changed) . , The HELj^.PRC need not be 
regenerated; it will always call up the newest version of the helpmodule 
file. ■ - 

If however, one wants ro change the lesson emphasis or other graph 
info in a, module, if the .VAL files are renamed or moved, s if new modules 
are to be added, or if the graph structure is changed in> any way, the 
changes must first be made in the graph and/or helpmodule files, and 
then HELPi^ mu^t be run to create^ a new version of HELP. PRC. 

Under the Modify option, only ti>e ' new files or those which have 
been \ changed need be processed. Unlike the procedure in. Create mode, 
second occurrences of a helpmodule for a topic will not be Ignored but* , 
rkther will cause the module to be redefined. The system will retain 
all information from the old system which is not superceded by the new - 
files- ■ ; n X . 

Note' that to delete a topic "trom the system, it is sufficient to 
remove it from the graph S-expression, and run HELPMK with the llodif y , 
option over the. new graph file, without reprocessing the helpmodule. 
file. The helpmodule will simply exist on 'a .VAL file but never be - 
accessed.. To , add a topic, to the system, however, both the graph file ■ 
and a helpmodule file must.be edited oand reprocessed. 



5 - Operation of the VOCAL Compiler and Interpreter , 

Once a lesson has been; written^ it must be tested and compiled. 
This is done using the VOCAL compiler, Va p^rogram that asisists authors in 
lesson testing and debugging and that produces various files needed for 
the audio system and course driver. This section .describes the 
operation and features of VOCAL. " 



Section 5.1 : ! ' , Initiklizing VOCAt 

5.1 Initializing VOCAL 

The leVson source files are usually- giveri names of the form 

-"<lesson>«VOC". -The -exact form ot^< 

■ . - ^ 

Whetf* VOCAL is. started, it prints a herald giving the program name 
and a "version number". The latter: consists of - the date and time that 
this version of VOCAL was compiled Then, before doings anythitjg else, 
VOCAL attempts to assign the-: audio channel associated wifch .the 
controlling^ terminal:' If there is none or if VOCAL is unable to assign 
it, it wili say, ''No audio channel assigned." If the MISS machine Is 
down, it will also say, "Audio syst^em . not available. " In any case, if 
the channel is assigned, VOCAL begins in AUDIO mode. If the audio 
.channel is not assigned, VOCAL will begin in DPY or TTY mode according 
to .the, type of the controlling terminal; /in these modes authors are 
subject to the VOGi^ conditional opcodes AIJDIO, NOHAUDIO, DPY, 'and TTY, 
described in'-Section 2.10. For example, in AUDIO mode VOCAL will not 
execute any action^ surrounded by ^ NONAUDIO, ,^ DPY. or TTY opcodes — and 
similarly for the other modes, this can be changed by use of the A, Y, 
or TTY commands described below." 

If VOCAL succeeds, in assigning the audio channel for the 
/^:ontr(Ollipg terminal, it will ask, "Do you want Long Sounds?",- followed 
by an "*", which is VOCAL's prompt character at 'this level. If ' the 
lesson has been recorded, the answer will usually be '*Y", otherwise "N" 
for "no" or Jiist a carriage-return which defaults to a. no answer. If 
the answer was no, VOCAL nexj: asks,' "DO you want PROSODY?" A "Y" answer 
to this question means that^ny audio messages will be spoken using the 
prosody system. ^ A carriage-return again defaults to a answer. : If no 
'audio channel was assigned, these two questions will be skipped. 



5.2 r Top-level V06AL Commands , 

• ."" . ' ' ■ • / "■'/■■'■■■ ^- . ■ _ .' ■ , ^ . ■ ^ \ 

'' After initiali^ I, G,, or ? This, 

is. the top command level for VOCAL, and there are numerous options 

available: 

? Print a list of the available options. / ^ 

T Enter Test mode. This mode allows the author to test ^a' 
lesson using code which has not yet. been compiled^ Test 
mode is described in Section 5.3. 

I Enter Interpret ,mode. This 'mode is much like test mode, 
except that VOCAL will read files that liave already been 
compiledi. See Section-S.A for details. ^ 

G Enter Generate files mode. This is the mode which allows 



For Stanford's logic course, the lessons have names of the form 
Lnnn.VOC, where nnn is^ a unique three-^igit number assigned to the 
particular lesson. Other courses may have different conventions. - 
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an author to compile a lesson. See Section* 5.5 for 
details. - ' ^ 

S Adjust:.„ the„. Speech rat e._pf._the.„.A^ 

. • ' current . implementation^ the default speech rate is' 0.9. 

' . ' This may be adjusted to -anywhere between 0.25 and 1.2. A 

small nuiaber increases the speech rate and a larger number 
* slows- it down. This 'has an effect only when testing or 
* -interpreting] a lesson in audio mode with an audio channel 

• . assi-gned. ' / 

A Select Audio mode. ^If an audio channel has been Assigned, 
VOCAL' will repeat the two questions ,concer_jiing^ "Long 
Sounds" and "Prosody". This provides a faster way of 
switching between the three modes than an exit -to the EXEC 
/ • . to obtain a. fre^h core image. If no audio channel is^ • 
assigned, VOCAL, will be set in a 'mode where if a lesson is 
tested or interpreted in audio mode, the text of \rfiatever 
.would have 'been spoken will print out in the SCROLL region 
of ^ the terminal prefaced by the word "SPEAK:". 

" i 

Y' ^Select displaY mode. .If a lesson is tested or - 
intgxpreted, the code within the scope of ^ DPY opcode 
will be executed.- 9 ■ ^ . , . - 

_ -TTY Select TeleTYpe mod.e. If a. ^lesson is tested or 
interpreted, the code within, the scope of a TTY opcode . 
' will be executed. i * 

ERR Interilipts the program with a pseudo user' error la order 
to enter DDT or other debugging f)rogram. This feature is 
V for the convenience of the pxogrannaers and is not normally 

needed by the lesson authors. 

. X Make a ^graceful eXit from VOCAL. Preferable to a ,""0 exit, 
- since all open f'iles will be properly reset and closed. 



; 5:3 • T~test- VOCAL Files Mode ^ - ' : ^* 

VThea an author enters Test iiK>de, VOCAL will begin by asking for a 
.file name; If the author wishes to be able to use the' TVEDIT text 
editor on theJEile while inside VOCAL, the file must be on the connected 
directory. No filename . recognition is done, but if the extension is the 
standard ".VOC" only the name field needs to be typed. 

Once a file has been sucess*«lly opened, VOCAL begins prompting 
with "==>" instead of "*" . ' In test mode, VOCAL files can be; ' compiled 
and tested one "object" . (i.e. , S-expression) at a time. No output files 
are generated. . The audio channel (if assigned) is open in "spell^^mode- 
(unless reset at connaand level using 'the "A" option!^ , so that lessons 
can be tested -without their Long Sounds or prosody. ^ ' . 

The 'commands available in. Test mode are: 



i 
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* ? ^ Print a list of the available options, A 

J * Jump, over page marks •'^ The author is asked how many to . 
. j ump rr W com^^ ; 

' Is faster than with "G", -Random access is nojt available 

at this stage, which limits the use of "J" to gbingO 
f orward, -Jumping "0" pagemark's resets the file to page 1, 

E Edit and Look Ahead.- As an aid to debugging, a simplified 
scanner is provided to "look ahead" on the current page. 
T^ie scanner prints out the text (suppressing the content ' . 
of strings) and checks for delimiter .mismatches and ' 
misspelled opcodes, , TVEDIT, the IMSSS text editor, is " 
available in this mode to' alter the VOCAL text. Upon 
return to Test mode, the file is reset to the beginning of 
the current page (thus a "G" must be executed to get and 
compile an object from it ) . The current pdge may be * 
chari^ed by using the "J" command. ' Dpon entering the 
scanner the author is prompted with "TV or Look". If .the < 
author then provides a "list of opcodes", the current page 
will be scanned for each, opcode in the list, in order. 
The delimiter scan wiir commence with the last opcode in^- - ^ > 
the list; The default is the first opcode on- the current. 
' pa-ge, and . typing TV . (carriage-return) take's the author 

^ , directly to the editor. 

G Get next object (S-expresslon) from file and' compile, it • 

I Interpret current object. NOTE: The interpreter will not 
interpret any derive-class opcodes, nor any branching ox 
f lag-alt eriijg opcodes. ^ / - 

D Display Current Coding. TKg^ current object (S-expression3 > ^. 
- is typed out for inspection. ^ 

C Compile ^rrent object (S-expression) . The current object 

i"S processed so that it can be interpreted using the I . 
command. . ■ . •■ x ■ 

V- 

0 Display- Current Output Coding. The compiled version of . 

the current object is typed out. Note that this is -not ■ ( -> 

t everything that goe's ir^o th^ ^inal output file (.VAL \ 

file) as a result of the "G" mode below. ' See the / 

discussion of the file fotmat in Appendix aI>* 

.1 . ■ ■ . ■ ■ . . ■ ■ . ■ ■ ■ . • - . 

■ ■ . ' ' . . . ■ ♦ ' _ < .. ■ ■ ^' . . ■ ' 

S Adjust the speech rate. ^ Same as the top-level S command* 

^ ■ ■ ' 'r ^ ■ - 

A Select Audio mode. Spme as t^e top-level A command. 

T . Select Teletype mode J \ Same as thfe top-level TTY command. 

. • • V:... • ' ^ ■ ' i • ■ ' • 

Y Select Displa;^ mode. Same as the" top-level D command. ^ ^ 

'/ P Select Prosody mode. Invokes the*pros©dy system. 



^ - 1" ■ i. ■ ■ 
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Q Select nonprosody mode. Resets the audio system from - 
prosody mpde to spell mode. ^ 

' * * • . ■ • 

_LJ Sele'ct__audio„symbol„ leCter.-___ Usef ul, when^^l^^ 

in which recorded -audio is present. iBy selecting the 
letter(s) used in •the\ file, an author " can [.feiaar all \ 
recorded messages while obtaining uni^ecorded messages in 
Spell mode. , * * • , 

• ' , ■ " ' ' ' \ • _ ■ ^ " 

LANGUAGE Select an^ audio language. this allows an authoic to . . 
change languages without restarting VOCAL. ■ ^ ^, ^ " 

•* . . ■ » ■ . 

ERR Intefrrupts the program with a;jpseudo user . error • Same as • 

th,e top^ level ERR command • . ' 

•X EXit Test mode. Returns control -to the top level.. Note' , 
that to completely exit VOCAL from inside Test mode, it is 
necessary to type two X''s. , . 



5.4 . I — Interpret Previously Compiled VOCAL iFil^s Mode 

Once a lesson file;^ has been 'compiled, it can be ..interpreted using 
VOCAL by entering Interpret mode. Juse^as in Test mod^, VOCAL begins, by 
asking for a file name. However, the default extension is VAL instead 
of VOC. AJLl VOCAL opcodes will work correctly in this mdde, 'except 
that, as in test -mode, derive^class, branching, and flag-alteration 
opcodes are not interpreted at all* VOCAL will usually detect major 
syntax errors within the scope of these opcodes and warn the author. 
But there are many kinds of errors that it cannot detect.' So it ±^ very 
important that a. compiled^ file " is, tested using the appropriate 
curriculum driver before the lesson is made available to students. 

, J ^ Jump to an. Exerciise. VOCAL then asks for the number. 
, ' Once the lesson, has ^been compiled, VOCAL can randomly - 
access the exercises; thus there ;ls no restriction about v 
going backward or, forward in tUe' lesson. , ^ ■: 

» ' ■ . 

I" Interpret Current' Exercise^ • 

G • to ,^ext ^" Exercise. . Goes ^ to the next higher number 
exerctse. If there is no .next higher numbered exercise^ 
■ . ' VOCAL will print a message to that effect-. 

'D Display Current Compiled Code. Print^ out the compiled S- 
.expression for inspection- Note that this is ^ only a part 
of , the compiled VOCAL file. . 'See ,the description of the ' 

file format in Appendix A. 

- ' . ■ ■ I ■ ' - ^ , . ^ p 

S ' Adjust the speech rate. Same' as the top-level S command. 
A Select Audio, mode. 'Same as the top-levfel A command. 

^ " ■ -r ' '' ^' \ ' ' ■ ' ■ ' '. 

^ T ' Select Teletype. mode.^2^Same as the • top-level TJY^ command. ^ 



Section 5.4 , I—Interpret Previously Compiled VOCAL Files Mode 

*".■'■•" • ' 

Y .Select Display mode. Sacie as the top-level D command. 

ERR Interrupts the program with a pseudo user error^ in Wder 
to enter DDT or other debugging program. * ' ^ 

X EXit Interpret mode. . Returns control to the top level. 
Note that to completely exit: VOCAL from litfside Interpret . 
mode.it is necessary to type two X'^s. ; 

5.5 G— Geoie^^te Compiled Files add Audio. Scripts Mode 

When an .author enters Generate Files mode, VOCAL begins by asking 
: for a filename. Like Test , mode, tHe default extension is VOC. Next, 
VOCAL will ask which version to comj)ile:. audio (A),, display (Y), or 
teletype (TTY). If audio is selected, the author has a choice of 
prosody or ^Long Sounds.''. If Long "Sounds are selected, VOCAL will ask 
for a. letter to precede the lesson number in the sound names in the 
script fi-Le.. This letter is used in making up the internal "name" of 
each Long. Sound. VOCAL will also ask whether it should retain . the 
audio text in the VAL file. This allows the file to be interpreted in 
Spell Mode. Normally, the audio text shozxld not be retained, but this 
is. .sometimes useful when the, audio messages are going to be recorded and 
an author wishes to use the curriculum driver to test the lesson before 
the recordings are: available. V . 

When a v;^sson file is conq)iled, the following files are produced: 

.VAL file. Thi$ is the file interpreted by the curriculum 
driver or by VOCAL in "I". mode. The internal file format 
■ is shown in Appendix A. . 

.SCP file. . This is the ^udio script which is, used to record 
the "long sounds "^f or the lesson. It is simply a list of . 
pairs of sou6d names (also called "audio symb.olis") and the 
text to be spoken. 

•BRA file. If PROSODY is selected, this file contains the 
spoken material ' in "bracketed" form. The bracketing 
represents the prosody module's idea of the syntactic 
structure of the. ma:terial to be spoken. \- 

.LST file. When compiled in Long Sounds mode, this file has 
/' the long sound names inserted in the "SN" opcodes. It may 
' be useful if part, but not allj of the lesson is to Be 
revised.* In that caise, the SN opcodes can be changed, back 
to S opcodes in the revised portion- (deleting: the- .sound 
names) and the lesson can be recompiled. ^No audio script 
will bd generated for the unchanged portiopis of the 
lesson.. When compiled in prosody mode, this file contains 



^Authors should see the supplement for their course to find out 
which letters are currently being used. 
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the bracketed strings in place of the original audio^ text- 
With * careful rebracketing> this file can be used to 
recompile for prosody* . : / . ..-^ 
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Appendix A . ; ^ "* File Format'for ^Compiled VOCAL Files 

' , Apbeadi^ A 
• ; ! ■ File Fotmkt for Compiled . VOCAL Files 



The-fil€ format for TEMPLATES .is: * 

* . -. ■ '. . ' If ' » • ^ ■ " ■■ • *" 

' .WORD 0: TOTAi: AREAS DEFINED (A2LAST) 

• ..' -AREAS IN lEMl REGION (AILAST) . 
.' 'TOTAL OF STRINGS (I2LAST) A 
■ • . ilNES IN TEMl REGION CIILAST) 

LENGTH OF STRINGS FOR ARRYIN/ARRYOUT (TEMSLENGTH) ■ 

.* COMPRESSED AREA DEFINITION TABLE (AR^ADEFS) . ^ 

^RELOCATABLE BYTEPOINTERS FOR STRINGS (TLINES) " ' 
COMPACTED STRINGS BUFFER (TEMSTRINGS) , ■ 

<S! EXPRESSION FOR AREA ASSOCIAtlON> (AREALIST) 

The file format for EXERCISES isr " 

WORD 0: <TEtIPLATE . !> " . ' ' " , 

'"CTEMPLAIE N> ■ 

<S! EXPRESSION FOR^jRAPH IIIF0>\ :. ^ . 

<SlEXPRESSION FOR EXERCISE> ' " 

INDEX: EXERCfSE V 

OF TEMPLATES ■ " ' ' /" ... ,^ . ■ 

'. ' WORD OF TEMPLATE 1, . ; • . " ■ 

WORD' OF templatE'/n; . -^^ ^ 

._ ; .CHARAGTER . OF pERCISE SiE2ffRESS^^^^^ ■ • 

, ■ " CHARACTER '. OF GRAPH INFO. S ! EXPRESSION ■ : , ^ " : - / 'i ■ ^ 

The file format- f or LESSONS is : 

WORD 0: WORD OF INDEX 

■ <LESSGN DESCRIPTOR> — "EXERCISE 0" 

<EXERCISE 1>- ' . • 

. <EXERCISE N> 
<LESSON DIRECTORY> — TEMPLATE FOR BROWSER 

INDEX: LESSON - . , 

OF EXERCISES 
WORD 'OF LESSON DESCRIPTOR. .' 
: . WORD .OF EXERCISE 1 INDEX 

• . WORD . OF EXERCISE N INDEX" * ■ ' ' ■ ' ■ . 

; ; WORD ■"OF LESSON DIRECTORY ' 
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Implemen tat ions of the S Opcode . 



Currently three implementations of the S opcode are being 
considered: "L^ng Sounds", "Prosody", and "SpelL Mode"w "Lo^S Sounds" 
means that the '"messages" are recorded c in segments of no. more than 4«5 
seconds duration.; If an individual "messi^e" is expected to be longer 
than 4.5 seconds, the lesson . author must divide it into two or more 
messages. "Prosody" will parse the "messages" into a bracketed spring 
("irvin-expression"), then generate a list of prosody specif icatlons 
("SIL-expr ess ion") -which will be passed to, the audio ^'^ystem for 
interpretation by the MISS . machine, "Spell Mode" is thd ' l^^son-author 
^test mode in iriiich the "messages" are simply spoken word ^by ' word, and 
TOrds not available in the audi^ lexicon are spelled out* 

As a further, aid to timing, a period encountered within a "message" 
will be followed by .500 ms x>f silence, any colon or. semicolon^ will be 
followed by 250 ms of silence^ and any comma will be foJLlowed by 125 ms 
of silence. 



14" . - ^ 



The cpmpiler produces a variety of internal forms for .the S opcode^ 
which may l>e retained by the author if he uses the ".LST" output file as 
his ^ource file. This-may be useful in the^pase of "Prosoiiy" as long as 
parsing, and: prpsing are^^iow/ processes. ISie syntax of thes*e internal 
forms is indidated below, but is. actually some;what- Store complex a:ad- 
. subject to ^ntinuing development. . , ^ 

j^-."-. (SN "name'V '^text :of *me^ssage'*> ; ; ; • . ^r.:' - 

>THe ,SN opcode is one of the opcodes into which the • S opcode may <:ompiiev 
--'^ VName" is the name of a - Long Sound (an entry in the audio lexicon)*. 
. "Text of message is the original text of • the messagfe , and is ; dropped- in 
the compiled form (unless explicitly ret;;ained>. This text is always 
. retained' in the* listing form /(which may become the source file).. ^nT" 

^ ^ ' (SB "bracketed text") 7 

"Braqketed text" is a prosody expression (an "Ai^viu-expression") that is 
to be prosodied and- spoken. 

. (SL "literal SPEAK text" "original text") 



"Literal / SPEAK text" is the "SIL-expression" that . should . be passed' 
directly to the SPEAK, audio library procedure. "Original. ^'text" is the 
ojigiiial text that produced this ancl is drbpped/in the compiled form but' 
retained in the source listing. * ^ 



/^^e actual duration , of ^silences is su^^ the implementation 

and may change. /. - ' : o : ' . 
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